feat: surface X-Logfire-Warning / X-Logfire-Error response headers#1906
feat: surface X-Logfire-Warning / X-Logfire-Error response headers#1906
Conversation
Adds a `requests` response hook that the SDK installs on every Logfire-bound HTTP session (OTLP exporters, token validation, CRUD client, variables provider, CLI). The hook reads two custom headers the server attaches to responses: * `X-Logfire-Warning` -> `warnings.warn(..., LogfireServerWarning)`. Python's default filter dedupes identical messages within a process, so a chatty server only warns once. * `X-Logfire-Error` -> raises `LogfireServerError`. OTLP/variables paths already swallow exceptions from their HTTP calls; CRUD/CLI propagate the error to the user. This gives the backend an out-of-band channel to deprecate endpoints or signal hard failures without piggy-backing on response bodies. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Deploying logfire-docs with
|
| Latest commit: |
4808b4f
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://a0d97e8d.logfire-docs.pages.dev |
| Branch Preview URL: | https://add-server-response-headers.logfire-docs.pages.dev |
Per review (#1905#discussion_r3189043209), the X-Logfire-Warning / X-Logfire-Error response-hook handling is logically independent from the X-Logfire-Telemetry request header — they just happened to be introduced together. Moved that code (plus its exceptions, install calls, and tests) to a separate PR (#1906) so each can be reviewed and landed on its own. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
| warnings.warn(warning_message, LogfireServerWarning, stacklevel=2) | ||
| error_message = response.headers.get(ERROR_HEADER_NAME) | ||
| if error_message: | ||
| raise LogfireServerError(error_message) |
There was a problem hiding this comment.
I worry that users might have a reason to opt out of this and won't be able to. Maybe that's paranoid.
We could theoretically make this hook configurable, defaulting to this one, but allowing users to take any action for all API responses. Probably overkill.
I'd like to know what concrete use cases we have in mind for both warnings and errors.
There was a problem hiding this comment.
I'd like to know what concrete use cases we have in mind for both warnings and errors.
From the PR description:
to deprecate endpoints or signal hard failures to any client running this SDK
There was a problem hiding this comment.
we'd deprecate endpoints by changing code here though, right? or is the point to push users to upgrade their sdk?
hard failures like what? where would the server respond with the error header instead of a 4xx/5xx which would have a similar effect here?
There was a problem hiding this comment.
Yes the point is that we can propagate deprecation to old versions of the SDK.
hard failures like what?
The error part was a bit more just "seems like it could be useful". But I imagine it might be more informative to raise a LogfireError: Some explanation Than hope the 4xx bubbles up correctly in a way that is usable by users.
I also wonder if we could emit an error / warn logfire log so it shows up in users projects 🤔
Lets users intercept every Logfire API response (OTLP exports, credential init, variables provider). Default keeps the existing X-Logfire-Warning / X-Logfire-Error handling; pass `lambda response: None` to opt out, or compose around `process_logfire_response_headers`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 5 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="logfire/_internal/config.py">
<violation number="1" location="logfire/_internal/config.py:1333">
P2: `_lazy_init_variable_provider` (line 1462) creates a `LogfireRemoteVariableProvider` without passing `transport_response_hook`, so lazily-initialized providers won't surface server warning/error headers. Add `transport_response_hook=self.advanced.transport_response_hook` there as well.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
The example references `logfire`/`my_metric` without imports, which test_docs runs through pytest-examples and trips on. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
`_lazy_init_variable_provider` was constructing `LogfireRemoteVariableProvider` without the configured hook, so providers spun up via the lazy path bypassed the user-supplied response handling. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2 participants
Summary
Split out from #1905 (per review).
Gives the Logfire backend an out-of-band channel — independent of response bodies — to deprecate endpoints or signal hard failures to any client running this SDK.
A new
logfire/_internal/server_response.pymodule installs arequestsresponse hook on every Logfire-bound HTTP session (OTLP exporters, token validation, CRUD client, variables provider, CLI). Each Logfire response is checked for two custom headers:X-Logfire-Warning: <message>warnings.warn(message, LogfireServerWarning). Python's default filter dedupes identical messages within a process, so a chatty server only warns once.X-Logfire-Error: <message>LogfireServerError. OTLP/variables paths already swallow exceptions from their HTTP calls; CRUD and CLI propagate the error to the user.Both headers are optional — absent headers are silently ignored, so the existing wire format is unaffected for clients running an older SDK.
Test plan
tests/test_server_response.pycovers warning emission, dedup, error raising, and end-to-end propagation throughLogfireClient.make format lint typecheckclean.uv run pytest tests/test_server_response.py tests/test_configure.py tests/test_client.py tests/test_variables.py tests/test_cli.py(451 tests) passes.🤖 Generated with Claude Code